-- card: 28813 from stack: in.0
-- bmap block id: 0
-- flags: 0000
-- background id: 3797
-- name: 


-- part contents for background part 1
----- text -----

From: mitch@well.UUCP (Mitchell Waite)

Date: 5 Mar 88 06:56:25 GMT

>>It [manual for software] is done last and fast.
>
I don't think you understand the process of documentation from the inside at
all.  In all the companies I've worked, the docs never came "fast and last".
The documentation team at Microsoft, for example, is included in product
development from the start. 
>

Sure, what do I know about documentation? But you're a lucky guy Mr. Arrants.
You have not had to dirty your hands with companies that ignore documentation.
But come off your tower, Microsoft is not the way it is everywhere. 

Sure,  over the last few years they have paid a great deal of attention to
documentation. I am just finishing writing a book on programming with Microsoft
Quick C for Microsoft Press, and have written several others for Microsoft
Press. I have had an opportunity to work with beta Quick C, watch the manuals go
through there revisions, and yes I am impressed. But that is just not the way it
in the vast majority of computer and software companies. Don't misread me. I
admire the improvements Microsoft has made in documentation, and it would be
nice if other companies followed their lead. I'm just saying that is not the way
it is in the vast majority of companies.

>
Nope.  What leaves these holes [in the documentation from software companies]
are:
1.  Changes to the software that can't make it into the documentation
because the books are either finishing the run at the printer or that
the books are in the warehouse waiting for the software to arrive for
shipping.
2.  Cost of Goods.  If a product sells to a distributor for, say $200,
COG can be 15% - $25.  That's $25 for the package, disks, disk labels,
keyboard templates, collateral materials, registration card, and
documentation.  Let's say that the documentation itself is 10% ($20)
COG.  I don't think that software companies are doing too poor a job.
The manuals MUST be comprehensive.  Third party books rarely are.
>

I won't say I think you know nothing about publishing, but the holes you mention
are mostly minor. The main ones are caused by the fact that manufacturers don't
take responsibility to teach people how to use their products. Instead they say
"Oh, you must already know how to program in C. We just tell you the "right"
syntax, the limitations, and if you are lucky we'll give you an example too".
The manuals cop out by only giving syntax and leaving the tutorials to other
folks. Why? I think its because most manufacturers are the poorest users of
their own products! Sorry, but I see it over and over. Its the ivory tower
syndrome. Lets see what other people think.

Yes, manuals, especially ones on complex products like languages and operating
systems, have to be comprehensive. So what are we suppose to think: don't expect
to learn anything from them? Certainly Microsoft offers more manual pounds per
dollar than any other company. But if these manuals where such a panacea, I
would not be writing this book.



-- part contents for background part 45
----- text -----
Re: HyperTalk Books, How to Judge?